Skip to content

Create security improvements for the project to ensure PROD-SAFETY#25

Merged
tomtastisch merged 14 commits intomainfrom
tomtastisch-patch-1
Feb 13, 2026
Merged

Create security improvements for the project to ensure PROD-SAFETY#25
tomtastisch merged 14 commits intomainfrom
tomtastisch-patch-1

Conversation

@tomtastisch
Copy link
Owner

@tomtastisch tomtastisch commented Feb 13, 2026

Initiative/Epic: Evidence-Härtung für

- SECURITY.md (frozen)

- externe Audits/Attestations

- vollständige Codeanalyse bis Codezeile

- Refactor-Backlog

Stand: 13. Februar 2026
Repo: GitHub (Code Scanning / Actions / Releases) + NuGet Package Publishing

Ausgangslage

SECURITY.md ist durch zwei Instanzen geprüft (bewertet als “human und umsetzbar”) und darf nicht mehr geändert werden.
Alle Aussagen werden daher vollständig über Code, CI-Checks, Audit-Artefakte und externe (kostenfreie/realistische) Audits technisch nachweisbar gemacht.

Zusätzliche relevante Auffälligkeit (GitHub Code Scanning Tool Status):

  • Warnung: “Low C# analysis quality”
  • Ursache: C# Extraction mit build-mode: none → Analyse ohne Build-Kontext (Risiko für false positives/false negatives)
  • Muss behoben werden (Auto-Build oder manuelle Build-Schritte), weil sonst Security-Aussagen nur eingeschränkt belastbar sind.

Leitprinzipien (Fixpunkte)

  • SECURITY.md bleibt unverändert (frozen).
  • „Nachweisbar“ = maschinell reproduzierbar (Script/CI) + persistiertes Ergebnisartefakt.
  • Fail-closed nur bei deterministischen Checks; sonst Tri-State: pass | fail | unknown mit klarer Reason.
  • Installierbare Konsolen-Tools sind erlaubt (CI und lokal), wenn sie die Evidence-Qualität erhöhen und Ergebnisse persistieren.
  • Ziel: Zertifikate/Attestations sichtbar im Repo und (soweit technisch sinnvoll) im NuGet-Paket dokumentieren/transportieren.
  • Der Plan führt das Projekt in die nächste Phase; Umsetzung erfolgt clusterweise mit Gates.

Cluster-Architektur (aufeinander aufbauend, sicher umsetzbar)

Cluster 0 — Guardrails & Result-Contract (Baseline)

Ziel: Keine unnötigen CI-Blockaden; saubere Definition von blockierend vs. report-only.

Deliverables

  • docs/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD
    • Statusmodell: pass|fail|unknown
    • Blocker-Regelwerk (nur deterministisch)
    • Evidence-Anforderungen (Artefaktpflicht, Schema)
  • Result-Contract:
    • Nutzung/Erweiterung des bestehenden tools/ci/schema/result.schema.json oder kompatibles Schema

Gate 0 (Abnahme)

  • Tri-State ist verbindlich; unknown wird nie still als fail interpretiert.

Cluster 1 — SECURITY.md Truth-Matrix (SSOT)

Ziel: Jede Aussage aus SECURITY.md wird vollständig gemappt.

Deliverables

  • docs/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD
    • Claim-ID (stabil, z. B. SEC-CLAIM-###)
    • SECURITY.md Anchor/Abschnitt (nicht primär line-number-only)
    • Claim, Evidence Source, Verification Command, Pass/Fail Criteria
    • Blocker-Flag, Limits/Unknown-Conditions

Gate 1

  • 100% Coverage: Jede SECURITY-Aussage hat Mapping.
  • Claims sind klassifiziert: blocker / report-only / unknown-allowed.

Cluster 2 — Evidence Engine (lokal + CI, deterministisch)

Ziel: Automatisierte Prüfung + persistierte Outputs (Logs/JSON/MD).

Deliverables

  • tools/audit/verify-security-claims.sh
  • Artefakt-Ausgabe:
    • artifacts/ci/security-claims-evidence/raw.log
    • artifacts/ci/security-claims-evidence/summary.md
    • artifacts/ci/security-claims-evidence/result.json (schema-valid)

Gate 2

  • Lokal reproduzierbar.
  • result.json schema-valid.
  • Negative/Unknown-Fälle korrekt klassifiziert und begründet.

Cluster 3 — CI-Integration (report-only → fail-closed)

Ziel: Sicher hochfahren, dann gezielt blockieren.

Phase 3.1: Report-only

  • .github/workflows/security-claims-evidence.yml (oder Erweiterung ci.yml)
  • Script ausführen + Artefakte uploaden + Job-Summary

Phase 3.2: Fail-closed (nur deterministische Blocker-Claims)

  • Blockade nur für Claims, die stabil prüfbar sind

Gate 3

  • Drift-Szenarien schlagen gezielt fehl (nicht flakey).
  • Unknown bleibt report-only (Standard), außer explizit als Blocker definiert (Ausnahme).

Cluster 4 — Externe Audits / Zertifikate / Attestations (Auswahl: “alle” oder “Minimum Set”)

Ziel: Konkrete, umsetzbare externe Nachweise (kostenfrei/realistisch) + verifizierbare Provenance.

4A — Pflicht (kostenfrei, extern verifizierbar, GitHub-native)

  1. OpenSSF Scorecard (Action, öffentlich verifizierbar)
  • .github/workflows/scorecard.yml
  • Persistenz: SARIF/Artefakt + Badge/Status im Repo
  1. GitHub Artifact Attestations (Build Provenance)
  • Release/Build: actions/attest-build-provenance
  • Verify: gh attestation verify ...
  • Persistenz: Evidence-Log + Verify-Output als Artefakt

4B — Optional, aber empfohlen (kostenfrei, “zertifikatsnah”)

  1. OpenSSF Best Practices Badge (Self-Certification, extern sichtbar)
  • Roadmap + Gap-Liste + Status-Dokument
  • Hinweis: Self-attested (kein formales Dritt-Audit), aber als strukturierte Benchmark gut

4C — NuGet-relevant (realistische Einordnung)

  1. NuGet Signing Strategy (Dokument + Prüfkommandos)
  • dotnet nuget verify (Package Signatur prüfen)
  • Autor-Signing optional: i. d. R. kostenpflichtiges Zertifikat nötig; self-signed wird bei nuget.org nicht akzeptiert

Deliverables (für Cluster 4)

  • docs/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD
    • Entscheidung: “Minimum Set” vs. “Alle”
    • Konkrete Umsetzungs-/Verifikationskommandos
    • Evidence-Outputs (wo gespeichert, wie geprüft)

Gate 4

  • Scorecard läuft + Ergebnis persistiert.
  • Attestation Verify läuft für Release-Artefakte.
  • Roadmap ist konkret und operational.

Cluster 5 — Sichtbarkeit: Zertifikate/Attestations im Repo und im NuGet-Paket

Ziel: Die Nachweise sind sichtbar “auffindbar”, nicht nur in CI-Logs.

Repo-Sichtbarkeit (Pflicht)

  • Badges/Status in README (oder dedizierter Audit-Index)
  • Audit-Index:
    • docs/audit/000_INDEX.md (Verlinkung auf Scorecard, Attestations, Findings, Threat Model, etc.)
  • Verifikationskommandos dokumentiert (copy/paste)

NuGet-Paket-Sichtbarkeit (zielorientiert, technisch sauber)

  • Paket-Metadaten:
    • RepositoryUrl, PackageProjectUrl, RepositoryType, PackageReadmeFile (NuGet)
  • Paket-Readme enthält:
    • Link zu Audit-Index
    • Link zu Scorecard Ergebnis
    • Kurze “How to verify provenance” (gh attestation verify) als Kommandos
  • Optional: Paket mit “provenance statement” (als Link, nicht als pseudo-Zertifikat)

Gate 5

  • Repo zeigt Nachweise sichtbar an.
  • NuGet-Paket referenziert nachvollziehbar die Nachweise (keine irreführenden “Zertifikat”-Claims).

Cluster 6 — CodeQL Quality Hardening (C# build-mode: none fix)

Ziel: belastbare Code Scanning Ergebnisse, sonst ist “Security Evidence” unvollständig.

Deliverables

  • Anpassung CodeQL Workflow (codeql.yml):
    • C# nicht mehr build-mode: none
    • Auto-Build oder manuelles dotnet restore + dotnet build passend zur Solution/Projects
  • Evidence:
    • Tool Status ohne “build-mode none” Hinweis oder signifikant bessere Metriken
    • Logs persistiert

Gate 6

  • Warnung “Low C# analysis quality” behoben oder minimalisiert + dokumentiert.

Cluster 7 — Vollständige Codeanalyse “vom Ablauf bis zur Codezeile” + Refactor-Backlog + Umsetzung

Ziel: Eine durchgezogene Analyse, die:

  • logische Abläufe (Call Graph, Data Flow) erfasst
  • bis zur einzelnen Codezeile Findings erzeugt
  • anschließend Refactors/Hardenings/Redundanzabbau in umsetzbaren Paketen durchführt

7A — Tooling (CI + lokal, installierbar)

Erlaubt sind installierbare Konsolen-Tools, wenn:

  • Ergebnisse reproduzierbar sind
  • Outputs persistiert werden (artifacts/audit/...)
  • Keine “Black Box” ohne nachvollziehbare Evidence

Deliverables

  • docs/audit/005_CODE_ANALYSIS_METHOD.MD
    • Analyse-Matrix pro Datei + pro Finding
    • Evidence-Anforderungen (Zeile/Beleg/Repro)
  • Baseline-Artefakte:
    • artifacts/audit/code_inventory.csv
    • artifacts/audit/callgraph_inventory.* (Format festlegen: JSON/CSV)
    • artifacts/audit/dead_code_candidates.csv
    • artifacts/audit/redundancy_candidates.csv
    • artifacts/audit/hardening_candidates.csv

7B — Findings (bis Codezeile)

  • docs/audit/006_CODE_REVIEW_FINDINGS.MD
    • pro Finding:
      • Datei + Zeile
      • Ablauf-/Kontext (welcher Pfad/Call Graph)
      • Risiko/Impact
      • reproduzierbarer Nachweis
      • konkrete Refactor-Änderung
      • Regressionstest-Vorschlag

7C — Refactor-Umsetzung (priorisiert, evidenzbasiert)

  • Findings werden in ein Triage-Board überführt (Severity/Impact/Effort)
  • Umsetzung in kleinen, reviewbaren PRs
  • Nach jeder PR:
    • Re-run der Evidence/CI Checks
    • Update der Findings (geschlossen/verschoben)

Gate 7

  • Jede Codezeilen-Finding ist reproduzierbar belegt (keine Vermutungen).
  • Refactors erfolgen paketiert, mit Tests und messbarer Verbesserung.

Cluster 8 — Governance-Closure (Threat Model, Incident Response, Supply Chain Baseline)

Ziel: vollständige Betriebs- und Auditfähigkeit.

Deliverables

  • docs/audit/007_THREAT_MODEL.MD
  • docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD
  • docs/audit/009_SUPPLY_CHAIN_BASELINE.MD

Gate 8

  • Konsistenz zu Truth-Matrix, CI Evidence, Attestations, Findings.

RISKS / Open Items / Mitigations (vollständig, priorisiert)

R1: “Zertifikat”-Wording kann irreführend sein (keine externe Auditstelle)

  • Mitigation: Strikte Trennung “Attestation/Assurance” vs “Formal Certification”
  • Policy: Keine Zertifizierungsbehauptungen ohne Dritt-Audit

R2: GitHub API / Permissions / Rate Limits → nicht deterministische Checks

  • Mitigation: Tri-State unknown + klare Reason
  • Blocker-Policy: keine blockierenden Claims, die auf unsichere API-Daten angewiesen sind

R3: CodeQL C# Quality (build-mode none) erzeugt unzuverlässige Findings

  • Mitigation: Cluster 6 als Pflicht vor tiefer “Security Evidence”-Argumentation

R4: Scope-Explosion (SECURITY Claims + Audits + Deep Code Analysis)

  • Mitigation: Gates + Cluster, klare Priorisierung
  • Erst Evidence-Gating stabilisieren, dann Deep-Analyse skalieren

R5: False Positives/Noise durch Tools (Scorecard/Qodana/Analyzers)

  • Mitigation: Baselines + Trend-Tracking + Triaging
  • Findings nur mit Repro und Impact klassifizieren

R6: Refactor-Risiko (Regressionen) bei großflächigem Hardening/Redundanzabbau

  • Mitigation: Kleine PRs, Testpflicht, Evidence-Checks nach jedem Merge
  • “No silent behavior change” Regeln (Dokumentation/Tests)

R7: NuGet Package “Zertifikate anzeigen” technisch missverständlich

  • Mitigation: Keine “Badge”-Behauptungen im Paket selbst; stattdessen:
    • Paket-Metadaten + Readme mit Links zu verifizierbaren Quellen
    • Provenance-Verifikation als Kommandos (gh attestation verify)

R8: Externe Audits abhängig von Repo-Visibility (Scorecard für private Repos eingeschränkt)

  • Mitigation: Wenn Repo privat: Scorecard Strategie neu bewerten (ggf. interner Lauf + Artefakt)
  • Entscheidung im Roadmap-Dok festhalten

Sichtbare Ergebnis-Outputs (Pflicht)

  • Repo:
    • docs/audit/000_INDEX.md als zentrale Startseite
    • Badges/Links (Scorecard/Attestations) sichtbar
  • CI Artefakte:
    • security-claims-evidence Artefakte je Run
    • CodeQL/Scorecard Outputs
  • NuGet:
    • Paket-Readme + Metadaten verlinken Audit-Index und Verifikationskommandos

Added a security policy document outlining supported versions and reporting procedures for vulnerabilities.

Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com>
Copilot AI review requested due to automatic review settings February 13, 2026 13:01
@github-actions github-actions bot added version:none No version bump required (meta-only change) chore Maintenance chore labels Feb 13, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Feb 13, 2026

Qodana for .NET

It seems all right 👌

No new problems were found according to the checks applied

💡 Qodana analysis was run in the pull request mode: only the changed files were checked
☁️ View the detailed Qodana report

Detected 6 dependencies

Third-party software list

This page lists the third-party software dependencies used in FileClassifier

Dependency Version Licenses
Microsoft.IO.RecyclableMemoryStream 3.0.1 MIT
Mime 3.8.0 MIT
MimeTypesMap 1.0.9 MIT
SharpCompress 0.39.0 MIT
System.IO.Hashing 10.0.2 MIT
ZstdSharp.Port 0.8.4 MIT
Contact Qodana team

Contact us at qodana-support@jetbrains.com

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a SECURITY.md security policy document intended to describe which versions receive security fixes and how to report vulnerabilities.

Changes:

  • Introduces SECURITY.md with sections for supported versions and vulnerability reporting.
  • Adds a supported-versions table (currently template/example content).
  • Adds a vulnerability reporting section (currently template placeholder text).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 13, 2026 14:38
@github-actions github-actions bot added docs Documentation change area:docs and removed chore Maintenance chore labels Feb 13, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@github-actions github-actions bot added feature New compatible feature or datatype area:pipeline and removed docs Documentation change labels Feb 13, 2026
Copilot AI review requested due to automatic review settings February 13, 2026 15:53
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 16 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 13, 2026 16:28
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 13, 2026 16:38
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 7 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 13, 2026 16:51
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 10 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 13, 2026 17:14
@tomtastisch tomtastisch changed the title Create SECURITY.md for security policy Create security improvements for the project to ensure PROD-SAFETY Feb 13, 2026
@tomtastisch tomtastisch merged commit 46f752c into main Feb 13, 2026
28 checks passed
@tomtastisch tomtastisch deleted the tomtastisch-patch-1 branch February 13, 2026 17:20
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +39 to +41
```bash
dotnet nuget verify artifacts/nuget/*.nupkg
gh attestation verify artifacts/nuget/*.nupkg --repo tomtastisch/FileClassifier
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These provenance verification commands reference artifacts/nuget/*.nupkg, which is a repo/CI output path and typically won’t exist for NuGet consumers reading the packaged README. Consider using a user-facing placeholder (e.g., <downloaded-package>.nupkg) and/or briefly stating that the .nupkg must be downloaded (from a GitHub release / local build output) before running dotnet nuget verify / gh attestation verify.

Suggested change
```bash
dotnet nuget verify artifacts/nuget/*.nupkg
gh attestation verify artifacts/nuget/*.nupkg --repo tomtastisch/FileClassifier
Laden Sie zunächst das gewünschte `.nupkg`-Paket herunter (z. B. aus einem GitHub-Release oder aus Ihrem lokalen Build-Ausgabeordner) und führen Sie dann die Verifikation aus:
```bash
dotnet nuget verify <downloaded-package>.nupkg
gh attestation verify <downloaded-package>.nupkg --repo tomtastisch/FileClassifier

Copilot uses AI. Check for mistakes.
Comment on lines 167 to 174
```bash
dotnet build FileClassifier.sln -v minimal
dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal
python3 tools/check-docs.py
bash tools/audit/verify-security-claims.sh
bash tools/audit/generate-code-analysis-json.sh
gh attestation verify artifacts/nuget/*.nupkg --repo tomtastisch/FileClassifier
python3 tools/check-policy-roc.py --out artifacts/policy_roc_matrix.tsv
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gh attestation verify artifacts/nuget/*.nupkg ... assumes a local artifacts/nuget directory exists and contains built packages. If this section is meant to be copy/paste reproducible from a clean checkout, consider either (a) adding the prerequisite build/pack step immediately before this command, or (b) using a placeholder path (e.g., <package>.nupkg) and clarifying where to obtain it (release asset vs. local pack output).

Copilot uses AI. Check for mistakes.
pathlib.Path(result_path).write_text(json.dumps(result, ensure_ascii=True), encoding="utf-8")
PY

if [[ "${STATUS}" != "pass" ]]; then
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script exits with code 1 for any non-pass status, which makes warn (intended to be report-only per the tri-state contract) fail the workflow run. If warn is meant to represent unknown/report-only, the script should still exit 0 and rely on result.json for reporting; only fail should be blocking.

Suggested change
if [[ "${STATUS}" != "pass" ]]; then
if [[ "${STATUS}" == "fail" ]]; then

Copilot uses AI. Check for mistakes.
Comment on lines +107 to +108
require_tool gh
require_tool jq
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

require_tool returns non-zero and is called under set -e, so missing gh/jq will cause the script to exit immediately before writing summary.md/result.json, violating the evidence contract. Consider recording the violation but continuing to the JSON emit path (e.g., call require_tool ... || true and include python3 in the required tools list).

Suggested change
require_tool gh
require_tool jq
require_tool python3
require_tool gh || true
require_tool jq || true

Copilot uses AI. Check for mistakes.
pathlib.Path(result_path).write_text(json.dumps(result, ensure_ascii=True), encoding="utf-8")
PY

if [[ "${STATUS}" != "pass" ]]; then
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script exits with code 1 for any non-pass status, so a warn result (intended to be report-only) will still fail the workflow run. If warn is meant to capture non-blocking findings, exit 0 for warn and only exit non-zero for fail.

Suggested change
if [[ "${STATUS}" != "pass" ]]; then
if [[ "${STATUS}" == "fail" ]]; then

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs area:pipeline feature New compatible feature or datatype impl:security version:none No version bump required (meta-only change)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant